Formatting Pattern in X

The formatting pattern allows a time number to be converted to a highly user-configurable, plain text format. When a time number is formatted, elements in the result are copies of the format pattern with format sequences replaced by the elements they represent.

The format sequences are intended to be visually reminiscent of the generated text. They use alphabetic characters easily associated with the substitution (for example, D, M and Y for Day, Month and Year respectively) repeated one or more times to indicate format. As noted below, some sequences allow the first character to be replaced by a _, or the casing to be altered.

The upper and lower case letters, underscore _, dollar $ and percent % are all reserved for introducing format sequences, even though not all currently have meaning. The remaining, non-reserved, characters are copied to the result unchanged, thus the format string hh:mm represents the hour of the day and minute of the hour with a colon between (for example, 12:00). All characters or sequences of characters may be delimited by " or ' at any point in the format string to prevent them being interpreted as a part of a format sequence, and, within these delimiters, two adjacent delimiter characters produce a single delimiter.

Note: The characters AaaaBbbb consist of two adjacent format sequences because there is a sequence of As followed by a sequence of Bs. The characters AaaaAaaa consist of one format sequence because it only contains As. It can be separated into two format sequences by inserting an empty " or ' - delimited string, for example, Aaaa""Aaaa.

Language

Unless overridden, English is used for text substitutions. Different languages may be selected using the Language variant option and/or the use of language specifiers within the format pattern. In either case, the language is specified as either a two letter ISO 639-1 language code in lower case (for example, en) or as a five character language with an additional underscore and two character region in upper case (for example, en_GB). Within the format pattern, __xx__ (where xx is the two or five character specifier) will switch the language of the subsequent generated text. Dictionaries for the following languages are built in:

Predefined patterns

Any pattern can contain (in part or in whole) a named predefined pattern, which allows common date and time formats to be specified in abbreviated form. Predefined patterns may be specified on a per-language basis, allowing patterns to be tailored for the selected language.

Predefined patterns are included in a pattern using % delimiters. For example, %ISO% includes the named predefined pattern ISO.

The following global predefined pattern is built in:

1. An ISO 8601 extended format calendar date and time with no time zone designator.

This list may be expanded in future.

Additional predefined patterns may be defined using the Dictionary variant option. Predefined patterns must not contain references to other predefined patterns.

Variant Options

The Language variant option specifies the language used for formatting datetimes and defaults to 'en' (English). The option value is a two or five character name (for example, 'en' or 'en_GB'). The setting may be explicitly overridden in the format pattern.

The Dictionary variant option specifies a namespace which contains additional or replacement names for the months etc. and/or predefined patterns, for languages and language regions.

At the top level there may be zero or more sub-namespaces with two or five character names, according to the rules for language and language regions. Within each of these, month names etc. are defined as follows:

Also at the top level of the dictionary namespace there may be a sub-namespace named Patterns and within this further sub-namespaces named Global and/or two or five character language names, containing definitions of predefined patterns. Predefined patterns are defined in the same way as the formatting pattern except that they may not contain references to other predefined patterns.

If the namespace contains a definition which is supplied built into the interpreter, it replaces the built-in one.

If a dictionary is incomplete (for example, if it is missing one of the expected named items, or one of the named items contains too few elements) an error is signalled only if the missing content would actually be needed.

      dict_json
{
  "Patterns": {
    "Global": {
      "ISOweek": "YYYY-'W'ww",
      "DateCompact": "D-MMM-YYYY",
      "DateVerbose": "'the date is' DD _mm YYYY"
    },
    "fr": {
      "DateVerbose": "'la date est le' DD mmm YYYY"
    },
    "en_US": {
      "DateVerbose": "'the date is' Mmm DD, YYYY"
    }
  },
  "en_US": {
    "ShortMonthNames": [
      "Jan.", "Feb.", "Mar.", "Apr.", "May", "June",
      "July", "Aug.", "Sept.", "Oct.", "Nov.", "Dec."
    ]
  },
  "cy": {
    "MonthNames": [
      "Ionawr", "Chwefror", "Mawrth", "Ebrill", "Mai", "Mehefin",
      "Gorffennaf", "Awst", "Medi", "Hydref", "Tachwedd", "Rhagfyr"
    ],
    "ShortMonthNames": [
      "Ion", "Chw", "Maw", "Ebr", "Mai", "Meh",
      "Gor", "Awst", "Medi", "Hyd", "Tach", "Rhag"
    ],
    "WeekdayNames": [
      "Dydd Sul", "Dydd Llun", "Dydd Mawrth", "Dydd Mercher",
      "Dydd Iau", "Dydd Gwener", "Dydd Sadwrn"
    ],
    "ShortWeekdayNames": [
      "Sul", "Llun", "Maw", "Mer", "Iau", "Gwen", "Sad"
    ],
    "MorningAfternoon": [
      "yb", "yh"
    ],
    "Ordinals": [
      "af", "il", "ydd", "ydd", "ed", "ed", "fed", "fed", "fed",
      "fed", "eg", "fed", "eg", "eg", "fed", "eg", "eg", "fed",
      "eg", "fed", "ain", "ain", "ain", "ain", "ain", "ain",
      "ain", "ain", "ain", "ain", "ain"
    ]
  }
}
      dict←⎕JSON dict_json

Note the following:

• In the example, the predefined pattern ISOweek is defined globally and is not redefined. It therefore has the same value for all languages. Similarly, DateCompact has the same value for all languages, but although the definition is global, it contains the pattern MMM and this will be substituted with the month name in the selected language.
• The predefined patterns DateVerbose is defined globally, and redefined for languages fr and en_US. The global definition will be used when any language other than fr and en_US is selected. If there was not global definition it would only be defined for fr, all regional variations of fr, and en_US.
• There is no explicit definition of patterns or names for language region en_GB. If this language is selected the definitions for en will be used.
• There is an explicit definition for ShortMonthNames for language region en_US. If this language is selected the definition of ShortMonthNames is as defined, and as for en for other names. As en is not defined in the dictionary, the built-in defaults are used.

In the following examples:

      tn←1 ⎕DT ⊂2019 2 13 10 16 56
      tn
43508.42843

English

      'Dddd, DDoo Mmmm YYYY; hh:mm:ss' (1200⌶) tn
 Wednesday, 13th February 2019; 10:16:56

      '__en__Dddd, DDoo Mmmm YYYY; hh:mm:ss' (1200⌶) tn
 Wednesday, 13th February 2019; 10:16:56

      '"ISO date": %ISO%' (1200⌶) tn
 ISO date: 2019-02-13T10:16:56

      '%DateVerbose%'(1200⌶⍠'Dictionary'dict) tn
 the date is 13 Feb 2019

English (US)

     fmt←'%DateVerbose%'
     fmt (1200⌶⍠('Dictionary'dict)('Language' 'en_US'))tn
 the date is Feb. 13, 2019 

Danish

      '__da__Dddd, DDoo mmmm YYYY; hh:mm:ss' (1200⌶) tn
 Onsdag, 13. februar 2019; 10:16:56

      fmt←'Dddd, DDoo mmmm YYYY; hh:mm:ss'
      fmt(1200⌶⍠'Language' 'da') tn
 Onsdag, 13. februar 2019; 10:16:56 

Welsh (using the dictionary defined above)

      fmt←'__cy__Dddd, DDoo mmmm YYYY; hh:mm:ss' 
      fmt (1200⌶⍠'Dictionary' dict) tn
 Dydd Mercher, 13eg chwefror 2019; 10:16:56 


      '__cy__%DateVerbose%' (1200⌶⍠'Dictionary' dict) tn
 the date is 13 Chw 2019